feat: Prometheus /metrics + TypeScript SDK + docs revamp#75
Merged
Conversation
Prometheus endpoint (no new dependencies):
- GET /metrics — standard text/plain; version=0.0.4 Prometheus scrape
target. Exposes releases_total, run_events_total, promoted_pointers_
total, actions_total, actions_by_type{action=}, pricing_tables_total,
schema_version. Same Bearer/loopback gate as GET /v1/metrics.
8 new tests in tests/test_prometheus_metrics.py.
Documented in docs/http-api.md with sample output + scrape config.
TypeScript SDK (sdk-ts/, package name: flightdeck-ai):
- FlightDeckClient: ingestEvent/s(), diff(), getWorkspace(), health()
using native fetch (Node 18+, zero deps).
- FlightDeckOpenAIAdapter: wraps openai.chat.completions.create(),
records tokens + latency + success as a RunEvent. Fire-and-forget.
- Types fully grounded in schemas/v1/run_event.schema.json and
src/flightdeck/models.py. No any casts except JSON deserialization.
- Retry on 429/5xx (3 attempts, exp backoff). X-FlightDeck-Actor and
X-Request-Id headers on every request.
- 584-line vitest suite: auth, retry, diff parsing, adapter latency,
cached tokens, fire-and-forget ingest errors.
- sdk-ts/README.md: install + 10-line quickstart + OpenAI snippet.
- Package name flightdeck-ai matches the PyPI package.
MkDocs docs revamp (--strict build passes, 0.33s):
- docs/getting-started.md (NEW): 'demo worked, now what?' — 5-step
guide from real release registration through promotion. The page
that was missing for first-time users.
- docs/index.md: 'Where to start' decision table (7 rows) above Quick
reference.
- docs/cli.md: 'Common patterns' section at top (4 copy-paste recipes:
register+diff, CI gate, weekly health, Slack webhook).
- docs/sdk.md: 'Quickstart' section at top (50-line annotated Python
example, end-to-end).
- docs/troubleshooting.md: 'First 5 things to check' numbered checklist.
- mkdocs.yml: Getting started added as second nav item.
Link cleanup:
- CHANGELOG.md: two GitHub blob /docs/cli.md links → hosted Pages URL.
- All other relative links left intact (GitHub renders them correctly).
Three audiences kept hitting dead ends: - 'I want to run this for my team' → no clear Postgres path - 'Is SQLite OK for prod?' → no guidance - 'How do I back up?' → pg_dump mention was buried Changes: - docs/getting-started.md: 'Production checklist' section — Postgres install (pip install 'flightdeck-ai[postgres]'), database_url YAML + env var, Bearer token for remote access, process supervisor guidance. - docs/operations-and-policy.md: SQLite vs PostgreSQL summary table near the top, links to existing detailed section. - docs/index.md: 'Deploy for a team in production' row added to the Where-to-start decision table. - examples/deploy/README.md: 'Using PostgreSQL' section with a complete docker-compose.postgres.yml snippet (postgres:16-alpine + flightdeck wired via FLIGHTDECK_DATABASE_URL).
MAJOR-1: sdk-ts/package.json: peerDependenciesOptional -> peerDependenciesMeta
peerDependenciesOptional is not a valid npm field (silently ignored,
causes unmet peer dep warnings on every install). Replaced with the
npm 7+ spec-compliant peerDependenciesMeta: { openai: { optional: true } }.
MAJOR-2: metrics.py: skip actions_by_type block when empty
Prometheus text format 0.0.4 prohibits HELP/TYPE headers with zero
time-series beneath them. Scraper warnings / rejections on fresh
workspaces. Wrapped the block in 'if actions_by_action:'.
MAJOR-3: test_prometheus_metrics.py: tighten content-type assertion
Was: 'text/plain' in content-type (too loose — any text/plain passes).
Now: startswith('text/plain; version=0.0.4') to catch regressions in
the full required header value.
CodeQL CWE-1333: /\/+$/ applied to user-supplied serverUrl flagged as potential ReDoS. While /\/+$/ is linear in V8, CodeQL cannot statically prove that and warns conservatively. Replaced with a plain while loop that is provably O(n) and CodeQL-safe.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three independently valuable additions in one PR:
1. Prometheus
/metricsscrape endpointGET /metrics— standardtext/plain; version=0.0.4Prometheus exposition formatGET /v1/metricsflightdeck_releases_total,flightdeck_run_events_total,flightdeck_promoted_pointers_total,flightdeck_actions_total,flightdeck_actions_by_type{action=},flightdeck_pricing_tables_total,flightdeck_schema_versiondocs/http-api.mdwith sample output + Prometheus scrape config YAML2. TypeScript / Node.js SDK (
sdk-ts/, package:flightdeck-ai)FlightDeckClient:ingestEvent/s(),diff(),getWorkspace(),health()using nativefetch(Node 18+, zero runtime deps)FlightDeckOpenAIAdapter: wrapsopenai.chat.completions.create(), records tokens + latency + success as aRunEvent(fire-and-forget)schemas/v1/run_event.schema.jsonandsrc/flightdeck/models.pyX-FlightDeck-ActorandX-Request-Idon every requestflightdeck-aimatches PyPI —npm install flightdeck-ai3. MkDocs docs revamp (
mkdocs build --strictpasses)docs/getting-started.md(NEW) — the "demo worked, now what?" bridge: 5 steps from real release registration to promotion with your actual agentdocs/index.md: "Where to start" decision table for first-time visitorsdocs/cli.md: "Common patterns" section at top (4 copy-paste recipes)docs/sdk.md: End-to-end quickstart example at topdocs/troubleshooting.md: "First 5 things to check" triage checklistVerification
ruff: cleanpytest --cov-fail-under=80: 210 passed / 4 skipped / 82.24% coverage (+8 Prometheus tests)mkdocs build --strict: 0.33s, no warningsPre-merge checklist
sdk-ts/— the TS SDK doesn't have a CI job yet (addnpm ci && npm run typecheck && npm testto a newsdk-tsjob in ci.yml if desired before publishing to npm)flightdeck-aion npm (separate workflow needed, similar torelease-pypi.yml)GET /metricsagainst a runningflightdeck servebefore tagging v1.4.0